Skip to content

fix(xvfb): wait for the display before starting the browser - #708

Merged
route merged 1 commit into
mainfrom
fix/xvfb-startup-race
Nov 19, 2026
Merged

route merged 1 commit into
mainfrom
fix/xvfb-startup-race

Conversation

@route

@route route commented Nov 19, 2026

Copy link
Copy Markdown
Member

Problem

With xvfb: true, headless: false the browser sometimes fails to launch with ProcessTimeoutError, long before :process_timeout runs out. Xvfb#start spawned Xvfb and returned immediately, so Chrome could start before the display accepted connections, fail to open it and exit. It showed up as a flaky spec/browser/xvfb_spec.rb on CI: https://github.com/rubycdp/ferrum/actions/runs/44533707075/job/135593471572

Fix

Xvfb is started with -displayfd, which makes it write the display number once it is ready to accept connections. Xvfb#start blocks on that for up to :process_timeout. If Xvfb exits or isn't ready in time, it is killed and Ferrum::Error is raised instead of launching a browser that can't find its display.

Spec

A new example launches a headful browser against an Xvfb wrapper that sleeps for a second before starting. It fails without the change and passes with it.

Xvfb#start returned right after spawning Xvfb, so a headful browser could start before the display accepted
connections, exit at once and surface as ProcessTimeoutError. Xvfb now reports readiness through -displayfd and
start blocks on it up to :process_timeout, raising Ferrum::Error when Xvfb exits or isn't ready in time.
@route
route merged commit 318e0a0 into main Nov 19, 2026
7 checks passed
@route
route deleted the fix/xvfb-startup-race branch November 19, 2026 15:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant